home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Camelot / Camelot 013 (1988-04)(Swedish User Group of Amiga)(SE)(PD)[WB].zip / Camelot 013 (1988-04)(Swedish User Group of Amiga)(SE)(PD)[WB].adf / Modula-2 / M2README
Text File  |  1988-04-14  |  6KB  |  136 lines
  1.                         ARP Modula-2 library bindings
  2.                         =============================
  3.  
  4.  
  5.      These modules are provided to let you access the many ARP functions from
  6. within any Modula-2 program. Two versions of each module is supplied, one for
  7. TDI Modula-2/Amiga and one for the Benchmark Modula-2 Construction Set.
  8.  
  9.      To use any of the procedures in the modules, you must first open the ARP
  10. library. This is done using the OpenLibrary() Exec call. It's just like opening
  11. any other library such as Intuition or Graphics. You will find an ArpLibrary
  12. module in which is declared the ArpBase variable. Use this variable to store
  13. the return value from OpenLibrary().
  14.  
  15.  
  16. Compatability
  17. -------------
  18.  
  19.      A lot of effort has gone into making these modules as similar as
  20. possible to the ARP library implementation in C, as well as to be consistent
  21. with the rest of the library modules provided by TDI or M2SCS. Hopefully, this
  22. will make your life easier when you try to use the ARP procedures for the
  23. first few times.
  24.  
  25.      Keeping this in mind, some minor changes had to be made to allow easy
  26. integration in a Modula-2 environment:
  27.  
  28.      -The AnchorPath record found in the ArpPatMatch.def module is missing the
  29. apBuf field at the end. This allows you to declare:
  30.           ExtendedAnchorPath = RECORD
  31.                                  anchor : AnchorPath;
  32.                                  buffer : ARRAY [0..511] OF CHAR;
  33.                                END;
  34.       You can include any size you want as array boundary in the buffer field.
  35. If apBuf was present, that declaration would not work properly, you would
  36. loose the first character in the buffer. The StdAnchorPath is provided in the
  37. ArpPatMatch module and uses a 256 byte buffer. Note that you MUST initialize
  38. the apLength field of the AnchorPath to reflect the actual length of your
  39. character buffer. This observation is repeated in the module itself.
  40.  
  41.  
  42. Startup
  43. -------
  44.  
  45.      The Modula-2 language as such doesn't specify any startup code. It is left
  46. up to the compiler developer to determine which startup code would best suit
  47. the system he is running on. The TDI Moudla-2 implementation has a startup code
  48. that initializes certain variables found in the AMIGAX module and then passes
  49. control to your main program. That means that YOU have to take care of parsing
  50. your command-line arguments or handling the message-passing stuff when started
  51. from Workbench.
  52.  
  53.      ARP comes to the rescue with its powerful GADS() function. It allows any
  54. program to provide the user with a consistent command-line interface similar to
  55. the one used by the standard AmigaDOS commands. On top of that, by using simple
  56. function calls, you can have your programs use the powerful wildcard
  57. capabilities of ARP.
  58.  
  59.      You can use the ARP function calls to prepare your command-line
  60. arguments, and do special-case code if your program is started from the WB.
  61. This is tedious and makes for awful looking code. Believe me, I know what I'm
  62. talking about!
  63.  
  64.      To simplify things, the ArpStartupCode module is provided. It contains
  65. two procedure calls, and four variables. Using the two procedures, you can have
  66. your program started either from CLI or Workbench, and then process the
  67. arguments you have received rather easily. The two procedures are:
  68.          -StartUp 
  69.          -CloseUp
  70.  
  71.      You call StartUp as the first statement in your program. You pass it a
  72. command template and an extra help string. Refer to the standard ARP
  73. documenttion to learn what these strings mean. When the function call returns,
  74. several things have been done for you:
  75.         - The ARP library has been opened.
  76.         - The DOS Library has been opened.
  77.         - The Intuition library has been opened.
  78.         - The Graphics Library has been opened.
  79.         - The module's variables have been initialized and are useable.
  80.         - When started from WB, your CurrentDir() will be set properly.
  81.         
  82.      The fact that all the libraries have been opened for you means that you do
  83. not need to call OpenLibrary() for every one of them in your main code. You do
  84. NOT (and shouldn't) need to CloseLibrary() them either.
  85.  
  86.      Four useful variables are aceessible in the startup module:
  87.      
  88.          myproc : This variable will point to your process. It equals
  89.                   FindTask(0)
  90.                   
  91.          numargs: Tells you how many arguments you received. This tells you how
  92.                   many arguments were on the command-line OR how many icons the
  93.                   user shift-clicked before double-clicking your program.
  94.                   
  95.          cliargs: This points to a buffer containing a series of CLIArg
  96.                   records which are used to describe the arguments received
  97.                   from CLI. If this value is NULL, its means your program was
  98.                   NOT started from CLI, you should then look at the wbargs
  99.                   variable to find the argument list.
  100.  
  101.          wbargs : This points to a buffer containing a series of WBArg records
  102.                   which are the arguments passed to your program by the
  103.                   Workbench MINUS the first argument. If this value is NULL,
  104.                   its means your program was NOT started from Workbench, you
  105.                   should then look at the cliargs variable to find the
  106.                   argument list.
  107.  
  108.  
  109.      Just before terminating, your program should call CloseUp. This routine
  110. will close the libraries, reply to the workbench message (if wb=TRUE) and
  111. return.
  112.  
  113.  
  114. Pattern Matching
  115. ----------------
  116.  
  117.      ARP provides some functions to support the standard AmigaDOS pattern
  118. matching (#?,(),{},etc...) as well as the ARP extensions ([],*). You can use
  119. those calls to make your program respond to wildcards. This ads a great deal of
  120. flexibility to your code.
  121.  
  122.  
  123. To Conclude
  124. -----------
  125.  
  126.      A sample program is provided to show how to use the startup code as well
  127. as how to use the pattern matching functions.
  128.  
  129.      I have tested and used most of the TDI modules, so they should be
  130. pretty much bug free. I did NOT extensively test the Benchmark M2SCS modules
  131. though, so if any problems arise, please report them as soon as possible so
  132. they can be fixed.
  133.  
  134.  
  135. -Martin Taillefer
  136.